POWER MANAGEMENT README
________________________

   This file contains a description of the
   Advanced Power Management specification as
   it applies to the OS/2* operating system.

OVERVIEW
________

   Power Management covers every aspect of power
   (AC/DC) consumption and utilization for
   personal computer systems.

   The main objectives of Power Management are to:

   o   Extend the battery life of mobile
       computers.

   o   Improve the utilization of mobile
       computing.

   o   Manage the power consumption
       characteristics of the system for both
       desktop and mobile computing environments.

   Advanced Power Management (APM) is an industry
   standard which covers the division of
   responsibilities for power management, between
   hardware and software.  The APM 1.0
   specification defines the APM BIOS Extension
   interfaces available to the operating system
   software layers.  APM 1.0 is a BIOS-level
   specification for power management.  The OS/2*
   Power Management subsystem supports and extends
   the APM 1.0 specification.  The OS/2 operating
   system runs on and will exploit the wide range
   of IBM* and other manufacturer's hardware that
   provide industry standard APM BIOS Extensions.

   To support Power Management, this release of
   the OS/2 operating system provides:

   o   Five new Generic IOCtl functions in a new
       category

   o   Four new inter-device communication
       commands

   o   Changes to 2 device driver helper functions
       (DevHlps)

   Additionally, there are some additions to the
   OS/2 device driver model.

   The MS-DOS 5.0+ Power Management Application
   Interfaces, INT 2FH - Function 54H, are not
   supported in the OS/2 DOS Session environments.


DEVICE DRIVER MODEL

   The OS/2 Device Driver Model has the following
   enhancements:

   1.  Optional usage of a new QUIET_FAILURE (15H)
       status-field error code for the device
       driver initialization commands (1BH - Base,
       00H - Installable).  The quiet failure
       return code suppresses messages and user
       prompts for the device driver's
       initialization failure.

   2.  Optional usage of a new device driver
       command, INIT_COMPLETE - 1FH.  This command
       is sent to every device driver that is
       loaded within this system startup and
       provides the device drivers a chance to
       establish links and dependencies which
       otherwise would have been resolved with
       load ordering dependencies in CONFIG.SYS.

   3.  Attach to or interact with the Power
       Management Services device driver (APM$)
       via new Power Management Inter-Device
       Communications (IDC) Interfaces.

       IDC participation is on a Notification
       level.  Notification enables device drivers
       to manage the device power state while
       allowing another parts of the system,
       typically the APM BIOS, to perform the
       manipulation of the device state.

   The new device driver initialization features
   are documented in the Toolkit's regular README
   file.


POWER MANAGEMENT DEVICES

   The set of device types supported by the APM
   1.0 Specification are:

   o   System BIOS (0000H)
       Device Id for APM BIOS itself.

   o   System BIOS managed devices (0001H)
       Generic device Id for all devices managed
       by APM BIOS.

   o   Display devices (01xxh)
       Generic device Id for display devices.

   o   Secondary Storage devices (02xxh)
       Generic device Id for secondary storage
       devices.

   o   Parallel Ports (03xxh)
       Generic device Id for parallel ports.

   o   Serial Ports (04xxh)
       Generic device Id for serial ports.

   Notes:

   1.  xx indicates the physical device number (0
       based).

   2.  All other device type values are reserved.

   3.  Devices powered with external system unit
       power supplies are not supported.


INTERNALLY VS. EXTERNALLY POWERED DEVICES

   An internally powered device is one which draws
   current from the system unit's power supply and
   has a direct line from the power supply which
   can be independently and uniquely controlled.
   An externally powered device is one which draws
   current from either a power supply outside of
   the system unit's or from an internal device
   that has no independent or unique control over
   the power line.  For instance, an asynchronous,
   serial port (COM) is an internally powered
   device, whereas the mouse connected to a COM
   port is considered an externally powered device
   since the current supply is not unique for the
   mouse.


POWER MANAGEMENT STATES

   The OS/2 device drivers should support the four
   Power Management power states with the
   appropriate device actions.  The set of power
   states supported by the APM 1.0 specification
   are:

   o   Ready (0000H)

       Indicates that the system or device is
       operating at full power.

   o   Standby (0001H)

       Indicates that the system or device is
       operating at a partial power level which
       permits improved energy conservation
       without noticeable power up delays for
       reestablished operation.

       Note:  There is not an explicit resume
       notification for the Standby state.  The
       implicit Standby resume is based upon the
       next time the associated code gets invoked.

   o   Suspend (0002H)

       Indicates that the system or device is
       operating at a partial power level which
       permits substantial energy conservation
       with accepted noticeable power up delays
       for reestablished operation.

       The APM 1.0 BIOS Interface Specification
       defines the Suspend power state as system
       wide state and does not currently support
       it as a device specific state. The OS/2
       architecture supports both system and
       device levels of usage as a desired
       deviation from the public standard.

   o   Off (0003H)

       Indicates that the system or device is not
       operating or receiving any amount of power.

   All other power state values are reserved.


POWER MANAGEMENT STATE DEFINITIONS

   The generic manner of OS/2 device driver
   support for Power Management's four power
   states is defined as follows:

   o   Ready State -

       State responsibilities can be described as:

       -   Enter State -

           Actions to properly enter state are
           more accurately defined by the prior
           state involved in the state transition,
           particularly for externally powered
           devices.

       -   State Operations -

           Operate at user desired throughput or
           at the currently defined levels (OS/2 2.0*)
           of performance with the assumption of
           full power.

       -   Exit State -

           Actions to properly exit this state are
           more accurately defined by the next
           state involved in the state transition,
           particularly for externally powered
           devices.

   o   Standby State -

       State responsibilities can be described as:

       -   Enter State -

           The current device state could be saved
           in RAM for most devices (both internal
           and external).

       -   State Operations -

           The device should be isolated from
           unnecessary commands and status
           activities which would consume power by
           bringing the device out of Standby.
           Useful commands could be processed by
           changing the state saved in RAM rather
           than programming the device
           immediately.

       -   Exit State - If a RAM-saved state is
           available and the saved information was
           modified during the Standby period then
           the saved values could be activated as
           delayed commands.  As a rule,
           internally powered devices need not
           have any additional support for this
           state.  However, externally powered
           devices (those that draw power from a
           port) should have device-state save and
           restore support.

           Note:  There is not an explicit Resume
           notification for the Standby state.
           The implicit Standby resume is based
           upon the next time the associated code
           gets invoked.

   o   Suspend State -

       State responsibilities can be described as:

       -   Enter State -

           All externally powered devices must
           have their device state information
           saved in a RAM data area. Similarly,
           all internally powered devices must
           have their device state information
           saved when the Suspend is on a device
           level rather than on a System/BIOS
           level.  Since no processing is
           permitted in the System Suspended
           state, internally powered devices can
           be left to the APM BIOS to save.

       -   State Operations -

           Since processing is not performed
           during this state, for System/BIOS
           requests there are no in-state
           operation requirements.  However, for a
           Device Suspend (versus a System/BIOS
           Suspend) the device driver must provide
           the isolation layer between the device
           and the applications.

       -   Exit State -

           All externally powered devices which
           had their prestate information saved
           should be reconfigured to bring them
           back to the pre-Suspend operating mode.
           This will also be the case for
           internally powered devices when a
           device-level Suspend exits.

   o   Off State -

       -   Enter State -

           Actions to properly enter this state
           include the complete device shutdown
           and disconnection from application
           environments. Since the device is not
           recoverable once this state is entered,
           all reconnect parameters must be saved
           to disk, if needed and applicable.

       -   State Operations -

           The device is now completely
           unavailable and operational activity
           must be shutdown or nonexistent.

       -   Exit State -

           Actions to properly exit this state are
           currently defined only as a restart of
           the entire system environment (both
           hardware and software).


POWER MANAGEMENT EVENT MESSAGES

   The OS/2 Power Management subsystem uses a
   messaging, event-driven interface.  The OS/2
   Power Management event messages are summarized
   in the table below, with the message specific
   parameter values.  The events reported via the
   Power Management Get Power Management Event
   function are a subset of the power management
   event messages available from the OS/2 Power
   Management Services Layer.  Messages with the
   word "Event" in the message name are reported
   directly from the APM BIOS interface.

   Ŀ
     OS/2 Power Management                                                
     Event Messages                  ulParm1               ulParm2        
                               SubId    | Reserved     (mesg-specific)    
   Ĵ
    Enable Pwr Mgt Functions   0003H      0000H       ---        ---    
   Ĵ
    Disable Pwr Mgt Functions  0004H      0000H       ---        ---    
   Ĵ
    Restore BIOS Defaults      0005H      0000H       ---        ---    
   Ĵ
    Set Power State            0006H      0000H      DevId    PwrState  
   Ĵ
    Battery Low Event          0007H      0000H       ---        ---    
   Ĵ
    Normal Resume Event        0008H      0000H       ---        ---    
   Ĵ
    Critical Resume Event      0009H      0000H       ---        ---    
   Ĵ
    Note:  All other values are reserved.                                   
   

   Figure 1. OS/2 Power Management Event Messages
             and Parameter values

   The general descriptions for each of the Power
   Management event message values follow.

   Note:  Many of the descriptions that follow use
   a C-language macro called MAKEULONG in the
   definition of the parameters.  A description of
   MAKEULONG is at the end of this section.

             Enable Power Management Function -
                       Indicates that the APM BIOS
                       request for power
                       management assistance is
                       being enabled.

                       Parameters:

                                   SubId(USHORT) = 0003H
                                   ulParm1 = MAKEULONG(SubId,0)
                                   ulParm2 = MAKEULONG(0,0)

                       Notification order:

                                 Device Drivers
                                 first.

             Disable Power Management Function -
                       Indicates that the APM BIOS
                       request for power
                       management assistance is
                       being disabled.

                       Parameters:

                                   SubId(USHORT) = 0004H
                                   ulParm1 = MAKEULONG(SubId,0)
                                   ulParm2 = MAKEULONG(0,0)

                       Notification order:

                                 Applications
                                 first.

             Restore BIOS Defaults - Indicates
                       that the APM BIOS Restore
                       BIOS Power On Defaults
                       request is being processed.

                       Parameters:

                                   SubId(USHORT) = 0005H
                                   ulParm1 = MAKEULONG(SubId,0)
                                   ulParm2 = MAKEULONG(0,0)

                       Notification order:

                                 Applications
                                 first.

             Set Power State - Indicates that an
                       APM BIOS Set Power State
                       function request is being
                       processed.

                       Parameters:

                                   SubId(USHORT) = 0006H
                                   DevId(USHORT) = (See below)
                                   PwrState(USHORT) = (See below)
                                   ulParm1 = MAKEULONG(SubId,0)
                                   ulParm2 = MAKEULONG(DevId,PwrState)

                                 Devid is the ID
                                 of the device
                                 whose power state
                                 is being set.
                                 The set of device
                                 types supported
                                 by the APM 1.0
                                 Specification are
                                 listed in POWER
                                 MANAGEMENT
                                 DEVICES, earlier
                                 in this document.

                                 PwrState is the
                                 state to which
                                 the device is to
                                 be set.  The set
                                 of power states
                                 supported by the
                                 APM 1.0
                                 specification are
                                 listed in POWER
                                 MANAGEMENT
                                 STATES, earlier
                                 in this document.

                       Notification order:

                                 Applications
                                 first.

             Battery Low Event - Indicates that
                       the APM BIOS has detected
                       and notified the operating
                       system that a Battery Low
                       situation is occurring.

                       Parameters:

                                   SubId(USHORT) = 0007H
                                   ulParm1 = MAKEULONG(SubId,0)
                                   ulParm2 = MAKEULONG(0,0)

                       Notification order:

                                 Applications
                                 first.

             Normal Resume Event - Indicates that
                       the APM BIOS has entered
                       and exited a normal system
                       suspend situation and is
                       notifying the operating
                       system on the suspend exit.

                       Parameters:

                                   SubId(USHORT) = 0008H
                                   ulParm1 = MAKEULONG(SubId,0)
                                   ulParm2 = MAKEULONG(0,0)

                       Notification order:

                                 Device Drivers
                                 first.

             Critical Resume Event - Indicates
                       that the APM BIOS has
                       entered and exited a
                       critical system suspend
                       situation and is notifying
                       the operating system on the
                       suspend exit.

                       Parameters:

                                   SubId(USHORT) = 0009H
                                   ulParm1 = MAKEULONG(SubId,0)
                                   ulParm2 = MAKEULONG(0,0)

                       Notification order:

                                 Device Drivers
                                 first.


MAKEULONG

   In the descriptions above, a C-language,
   defined macro called MAKEULONG is sometimes
   used in the definition of the parameters.
   MAKEULONG is defined in OS2DEF.H and has the
   following syntax:

          MAKEULONG(Low, High)

          /* Low and High are both 16-bit parameters. */

   Leaving out the type-casting for simplicity,
   MAKEULONG de-references to:

          ( (Low) | (High) << 16 )

   An example is:

          ULONG ulParm;

          ulParm = MAKEULONG(0x5678, 0x1234);

          /* The statement above sets ulParm equal to 0x12345678 */

   Note that the first parameter to MAKEULONG
   becomes the low-order word and the second
   parameter becomes the high-order word in the
   resulting 32-bit value.


INTER-DEVICE COMMUNICATIONS
___________________________

   In the OS/2 operating system, there is an
   interface layer among the low level subsystems
   and device driver clients.  The mechanism for
   achieving this interface is based on
   Inter-Device Driver Communications (IDC).  For
   the OS/2 Power Management Services Layer there
   are four IDC functions.  The IDC functional
   interfaces, and how they are mapped to the APM
   BIOS Interfaces, are defined in Figure 2.

   Ŀ
          APM 1.0 BIOS Functions       OS/2 Power Management IDC Functions 
   Ĵ
    Installation Check (00H)           QueryPowerInfo (0004H)              
   Ĵ
    Interface Connect (01H)            N/A                                 
   Ĵ
    Protect Mode Connect 16-Bit (02H)  N/A                                 
   Ĵ
    Protect Mode Connect 32-Bit (03H)  N/A                                 
   Ĵ
    Interface Disconnect (04H)         N/A                                 
   Ĵ
    CPU Idle (05H)                     N/A                                 
   Ĵ
    CPU Busy (06H)                     N/A                                 
   Ĵ
    Set Power State (07H)              SendPowerEvent (0002H)              
   Ĵ
    Enable/Disable Pwr Mgt Fcns (08H)  SendPowerEvent (0002H)              
   Ĵ
    Restore BIOS Defaults (09H)        SendPowerEvent (0002H)              
   Ĵ
    Get Power Status (0AH)             QueryPowerStatus (0003H)            
   Ĵ
    Get Pwr Mgt Event (0BH)            RegisterDDRtn/DeregisterDDRtn       
                                             (0000H)/(0001H)               
   Ĵ
    Note:  All other values are reserved.                                   
   

   Figure 2. APM BIOS to OS/2 IDC Function Map

   An OS/2 physical device driver accesses the
   Power Management services by calling the Power
   Management device driver's IDC entry point.
   This address is obtained using the AttachDD
   Device Helper (DevHlp) interface.  The name
   "APM$    ", (APM$ followed by four blank
   characters) should be passed to AttachDD as the
   Power Management device driver name.

   Before calling the Power Management device
   driver, the client device driver must create a
   data structure and fill in the appropriate
   parameters.  The first member of the structure
   is a WORD which identifies the function being
   requested.  The rest of the data structure
   contains the parameters for that function.

   The client then loads a Selector:Offset pointer
   to the structure into ES:BX, and calls the
   Power Management IDC interface.  There is no
   need to set the Power Management Data Selector
   before the call.

   On entry to the Power Management IDC routine
   ES:BX points to a data structure of the format:

     Function      WORD        ; IDC function code, as defined below.
     Parameters    BYTE(?)     ; Parameter packet, as defined below.
                               ; A different parameter packet is defined
                               ; for each IDC service.

   The Power Management device driver will process
   the call and return the Return Code in AX.  AX
   is set to 0 and the Carry Flag is cleared on a
   successful call.  On error, AX is guaranteed to
   be nonzero and the Carry Flag will be set.

   When a Power Management Event is triggered, the
   Power Management device driver will format an
   Event Notification Packet (as defined below),
   save a 16:16 pointer to the packet in ES:BX,
   set the client's DS selector, then call the
   client device driver.


POWER MANAGEMENT IDC SERVICES

   The OS/2 Power Management IDC function codes
   (the value in the first WORD of the data
   structure that is submitted to the Power
   Management IDC server) are defined as follows.

     Length    Value    Function
     ------    -----    --------
     WORD        0      RegisterDDRtn
                 1      DeregisterDDRtn
                 2      SendPowerEvent
                 3      QueryPowerStatus
                 4      QueryPowerInfo

     All other values are reserved.

   The OS/2 Power Management IDC functional
   descriptions are defined as follows:

   Power Management IDC Function 0 - RegisterDDRtn


             The RegisterDDRtn Function is used by
             a Power-Management-sensitive device
             driver that wants to get
             notifications of Power Management
             Events.  These Power Management
             Events are synchronous event
             messages.  The caller provides the
             following parameter information:

             Parameters

                           Field                Type       Length
                           -----                ------     ------
                           Handle               USHORT     WORD
                           EventHandler         PFN        DWORD
                           NotificationMask     ULONG      DWORD
                           ClientDS             SEL        WORD
                           DeviceId             USHORT     WORD

                         Where the fields are
                         interpreted as follows:

                         o   Handle

                             Output parameter.
                             The unique handle
                             value for the
                             registered
                             event-handler routine
                             information. Once
                             registered, a device
                             driver is required to
                             perform a
                             DeregisterDDRtn
                             request to disconnect
                             the registered
                             routine.

                         o   EventHandler

                             Input parameter.  The
                             calling device
                             driver's
                             Selector:Offset value
                             of the calling device
                             driver's
                             event-handler
                             routine.

                         o   Notification Mask

                             Input parameter.  The
                             bit mask indicating
                             the Power Management
                             Events the calling
                             device driver wants
                             notifications on.  A
                             set bit (value = 1)
                             indicates Power
                             Management Event
                             notification
                             selection. The
                             Notification Mask bit
                             definitions are:

                               BIT #      MEANING
                               -----      ---------------------
                                 3        Enable Power Management
                                 4        Disable Power Management
                                 5        Restore BIOS Defaults
                                 6        Set Power State
                                 7        Battery Low Event
                                 8        Normal Resume Event
                                 9        Critical Resume Event

                               All other bits are reserved.

                             See POWER MANAGEMENT
                             EVENT MESSAGES for
                             more details on the
                             Power Management
                             Event descriptions
                             above.

                         o   DeviceDS

                             Input parameter.  The
                             calling device
                             driver's Data Segment
                             Selector value.  This
                             selector value will
                             be loaded into the DS
                             register when the
                             Notification Routine
                             is invoked.

                         o   DeviceId

                             Input parameter.  The
                             ID of the device.
                             The set of device
                             types supported by
                             the APM 1.0
                             Specification are
                             listed in POWER
                             MANAGEMENT DEVICES,
                             earlier in this
                             document.  This
                             parameter can be used
                             to restrict the
                             notification of power
                             state changes.  The
                             parameter should
                             normally be set to
                             0001H, which selects
                             all BIOS managed
                             devices.  However, if
                             set to some other
                             value which selects a
                             particular device
                             type, the client will
                             receive notification
                             only on power
                             transitions on that
                             particular device.

                             For example, suppose
                             that a driver has
                             registered with
                             DeviceID set to 02FF
                             (all disk devices).
                             The Event
                             Notification routine
                             will be called
                             whenever:

                             -   the entire system
                                 is entering or
                                 exiting Standby
                                 or Suspend mode,
                                 or
                             -   when only some
                                 disk is entering
                                 or exiting
                                 Standby or
                                 Suspend

                             The Event
                             Notification routine
                             will not be invoked,
                             however, when, for
                             example, only a
                             display is entering
                             Standby.

             Remarks     Registered device driver
                         notification routines are
                         called with the following
                         Power Management Event
                         related information and
                         conditions:

                           Field        Type       Length
                           -----        ------     ------
                           Function     USHORT     WORD
                           ulParm1      ULONG      DWORD
                           ulParm2      ULONG      DWORD

                         Where the fields are
                         interpreted as follows:

                         o   Function

                             Input parameter.
                             Must be the following
                             value:

                             -   Event
                                 Notification =
                                 0000H.

                             All other values are
                             reserved.

                         o   ulParm1

                             Input parameter.  See
                             Figure 1 and POWER
                             MANAGEMENT EVENT
                             MESSAGES for value
                             descriptions.

                         o   ulParm2

                             Input parameter.  See
                             Figure 1 and POWER
                             MANAGEMENT EVENT
                             MESSAGES for value
                             descriptions.

                         The Power Management
                         Services device driver
                         loads the DS register and
                         calls the event-handler
                         routine address with the
                         values established with
                         the RegisterDDRtn
                         function.

                         On return from the
                         event-handler routine,
                         the Carry Flag (CF) must
                         be clear and the AX
                         register must be set to 0
                         (zero).  All other
                         register values are
                         preserved across the
                         call.

   Power Management IDC Function 1 -
             DeregisterDDRtn

             The DeregisterDDRtn Function is used
             by a Power-Management-sensitive
             device driver to disconnect a
             registered event-handler routine.
             This is necessary for proper cleanup
             in cases where a device driver wishes
             to deinstall after registration has
             occurred.

             Parameters

                           Field      Type       Length
                           -----      ------     ------
                           Handle     USHORT     WORD

                         Where the field is
                         interpreted as follows:

                         o   Handle

                             Input parameter.  The
                             unique handle value
                             for the device
                             driver's registered
                             event-handler
                             routine.  This value
                             is returned from a
                             successful request to
                             the RegisterDDRtn
                             function.

             Remarks     None.

   Power Management IDC Function 2 -
             SendPowerEvent

             The SendPowerEvent Function enables a
             Power-Management-sensitive device
             driver to send a Power Management
             event message to Power Management
             Services.  Power Management Services
             will process Power Management event
             messages sent by the device driver in
             the same manner as Power Management
             BIOS and user interface requests.
             This function might not return to the
             caller until the request and
             associated activities are completed.
             The caller provides the following
             parameter information:

             Parameters  Identical to Category 12,
                         Function 40H IOCtl's
                         Parameter Packet (shown
                         later in this document).

             Remarks     This function should not
                         be called if the caller
                         is running under the
                         context of the
                         IDC-registered device
                         driver event-handler
                         routine.  In addition,
                         this function should not
                         be called when running in
                         an interrupt context.

   Power Management IDC Function 3 -
             QueryPowerStatus

             The QueryPowerStatus Function is used
             by an Power-Management-sensitive
             device driver which wants to
             determine the current power source
             status.

             Parameters  Identical to Category 12,
                         Function 61H IOCtl's
                         Parameter Packet (shown
                         later in this document).

             Remarks     None

   Power Management IDC Function 4 -
             QueryPowerInfo

             The QueryPowerInfo Function is used
             by an Power-Management-sensitive
             device driver which wants to
             determine the power configuration and
             revision level information.

             Parameters  Identical to Category 12,
                         Function 62H IOCtl's
                         Parameter Packet (shown
                         later in this document).

             Remarks     None.


IDC ERROR CODES

   In addition to the error codes listed under the
   IOCtl return errors (see IOCTLS, later in this
   document), the following error codes might be
   returned:

   Ŀ
    Decimal  Name (Hex Value) and Description  
    Value                                      
   Ĵ
    128      PowerIDC_InvalidFunction (0080H). 
             IDC function code out of range.   
   Ĵ
    129      PowerIDC_InvalidHandle (0081H).   
             IDC handle invalid.               
   Ĵ
    130      PowerIDC_TooManyClients (0082H).  
             Maximum number of IDC clients has 
             been exceeded.                    
   Ĵ
    131      PowerIDC_Busy (0083H).  The       
             request can not be serviced at    
             this time due to pending activity 
             which must be completed.  The     
             caller must determine whether to  
             wait and reissue the request,     
             proceed anyway, or abort the      
             activity.                         
   


DEVICE HELPER FUNCTIONS (DEVHLPS)
_________________________________

   To support Power Management, some changes have
   been made to two of the Device Helper (DevHlp)
   functions.


SENDEVENT DEVHLP

   This interface is documented in the Physical
   Device Driver Reference on page 17-84.  To the
   Remarks section of the SendEvent documentation,
   where it is describing how the events are
   defined, add the following:

   o   System Power Event Notification

       -   Event = 9
       -   Argument = Power Event ID.
           The Power Event ID value supported is:
           0 = System Suspend.  All other values
           are reserved.


GETDOSVAR DEVHLP

   This interface is documented in the Physical
   Device Driver Reference on page 17-36.  To the
   GetDOSVar documentation, add the following two
   entries.  To the table of read only variables,
   add the following entry:


       Ŀ
        Index     Variable Description          
       Ĵ
         16       APMInfo:APMStruc.             
                  Advanced Power Management     
                  BIOS Information.  See below. 
       


   Following the read-only-variables table there
   are descriptions of the variables in the table.
   To the list of variable descriptions, add the
   following description of the new variable:


       APMInfo   Advanced Power Management BIOS
                 Information

                 APM_CodeSeg (WORD). APM 16-bit
                               code segment (real
                               mode segment base
                               address).
                               From APM BIOS, INT
                               15H AX=5302H.

                 APM_DataSeg (WORD). APM 16-bit
                               data segment (real
                               mode segment base
                               address).
                               From APM BIOS, INT
                               15H AX=5302H.

                 APM_Offset  (WORD). Offset to
                               entry point.
                               From APM BIOS, INT
                               15H AX=5302H.

                 APM_Flags   (WORD). APM
                               Capability flags.
                               From APM BIOS, INT
                               15H AX=5300H.

                 APM_Level   (WORD). APM revision
                               level.
                               From APM BIOS, INT
                               15H AX=5300H.

                 APM_CPUIdle (6 bytes (DF)). APM
                               Services Entry
                               Point for CPU Idle
                               Function.

                 Note:  APM_CodeSeg and
                 APM_DataSeg are segment
                 addresses, not selectors.  It is
                 the responsibility of the device
                 driver to convert the segment
                 address to a valid protect mode
                 selector.

   The first time GetDOSVar is called at device
   driver initialization time with index (AL) =
   10H and CX = 1, the system will set the values
   for APM_CodeSeg, APM_DataSeg, APM_Offset,
   APM_Flags, and APM_Level. On return return
   AX:BX will point to the APM_Info structure.

   If GetDOSVar is called at device driver
   initialization time with index (AL) = 10H and
   CX = 0, the system will set the values for
   APM_Flags and APM_Level. On return, AX:BX will
   point to the APM_Info structure. Other fields
   in the APM_Info structure might have been set
   by a previous call to GetDOSVar with index =
   10H and CX = 1.

   If GetDOSVar is called after device driver
   initialization time with index (AL) = 10H, no
   information in the APM_Info structure will be
   modified. On return, AX:BX will point to the
   APM_Info structure.

   APM_CPUIdle contains the address of the CPU
   Idle processing routine from the Power
   Management Services device driver.  This
   variable is initially empty (NULL) until Power
   Management Services loads and places it's CPU
   Idle routine address into the variable area.
   The variable address should be the 16:16
   Selector:Offset.  The Offset is zero-extended
   to 32 bits and the value should be represented
   as a 16:32 format.


IOCTLS
______

   In the OS/2 operating system there is an
   interface layer between the low level
   subsystems and the user interface environment.
   A typical mechanism for bridging between these
   layers, when device drivers are involved, is
   with the Generic IOCtl Interface.  For the OS/2
   Power Management Services Layer, the Generic
   IOCtl Category value of 12 is used for this
   interface.  The function codes supported are
   defined with the following common descriptions:

   o   Set/Send functions = 0100xxxxB.
   o   Get/Query functions = 0110xxxxB.

   The Generic IOCtl interfaces, and how they are
   mapped to the APM BIOS Interfaces, are defined
   in Figure 3, below.

   Ŀ
          APM 1.0 BIOS Functions           OS/2 Power Management IOCtls    
   Ĵ
    Installation Check (00H)           Query Power Info (Function 62H)*    
   Ĵ
    Interface Connect (01H)            N/A                                 
   Ĵ
    Protect Mode Connect 16-Bit (02H)  N/A                                 
   Ĵ
    Protect Mode Connect 32-Bit (03H)  N/A                                 
   Ĵ
    Interface Disconnect (04H)         N/A                                 
   Ĵ
    CPU Idle (05H)                     N/A                                 
   Ĵ
    CPU Busy (06H)                     N/A                                 
   Ĵ
    Set Power State (07H)              Send Power Event (Function 40H)     
   Ĵ
    Enable/Disable Pwr Mgt Fcns (08H)  Send Power Event (Function 40H)     
   Ĵ
    Restore BIOS Defaults (09H)        Send Power Event (Function 40H)     
   Ĵ
    Get Power Status (0AH)             Query Power Status (Function 60H)   
   Ĵ
    Get Pwr Mgt Event (0BH)            Query Power Event (Function 61H)    
   Ĵ
    N/A                                Set Power Event Res (Function 41H)  
   Ĵ
    * Some of the information available in the Installation Check function  
      is made available in the Query Power Info IOCtl.                      
   

   Figure 3. APM BIOS to OS/2 IOCtl Map

   The OS/2 Power Management IOCtl descriptions
   are defined as follows:

   Function 40H - Send Power Event

             This function enables the caller to
             initiate a Power Management Event
             through the Power Management Services
             subsystem and system clients.

             Parameter Packet Format
                       All parameter packet fields
                       are input fields for this
                       function.

                         Field                Length
                         ----------------     ------
                         ulParm1              DWORD
                         ulParm2              DWORD

                       The ulParm1 and ulParm2
                       fields are used the same as
                       defined for the Power
                       Management event messages.
                       See Figure 1 and POWER
                       MANAGEMENT EVENT MESSAGES,
                       earlier in this document,
                       for further details.

             Data Packet Format
                       All data packet fields are
                       output fields for this
                       function.

                         Field                Length
                         ----------------     ------
                         ReturnCode           WORD

                       ReturnCode is the
                       function-specific
                       completion value.  The
                       valid return values are:

                       o   PowerNoError
                           (0000H)
                       o   PowerBadSubId
                           (0001H)
                       o   PowerBadReserved
                           (0002H)
                       o   PowerBadDevId
                           (0003H)
                       o   PowerBadPwrState
                           (0004H)
                       o   PowerDisabled
                           (0009H)

             Returns
                       The ReturnCode field in the
                       Data Packet.

                       When an error condition is
                       encountered with an input
                       packet field (Parameter or
                       Data) the INVALID_PARAMETER
                       IOCtl error code (8113H) is
                       returned to the caller. The
                       caller must then inspect
                       the Data Packet's
                       ReturnCode field to
                       determine the specific
                       nature of the failure.

             Remarks
                       The SubId values allowed in
                       the ulParm1 field are
                       limited to values 0002H
                       thru 0006H. If the caller
                       requests a SubId value
                       outside of this supported
                       range the request will
                       return a with PowerBadSubId
                       error code.

                       When Power Management has
                       been disabled (SubId=0004H)
                       all requests except Power
                       Management Enable
                       (SubId=0003H) will fail and
                       be returned to the caller
                       with a ReturnCode value of
                       PowerDisabled.

   Function 41H - Set Power Event Res

             This function enables the caller to
             manipulate the resource set used to
             communicate with the Power Management
             subsystem. The Parameter Packet
             fields enable the caller to customize
             the resource set to fit the
             communication protocol desired.

             Parameter Packet Format
                       All parameter packet fields
                       are input fields for this
                       function.

                         Field                Length
                         ----------------     ------
                         ReqFlags             WORD
                         SemHandle            DWORD
                         EventMask            DWORD

                       ReqFlags is a bit mask with
                       the following bit
                       definitions:

                         Bit #    Meaning If Set
                         -----    -------------------
                          0       SemSetup request
                          1       SemRemoval request
                          2       16BitSemFlag
                          3       32BitSemFlag
                          4       NoSemFlag

                         All other bits are reserved and must be 0.

                       If any of the reserved bits
                       in the ReqFlags field are
                       set (value = 1), the
                       request will fail with a
                       ReturnCode value of
                       PowerBadReserved.

                       SemSetup requests (bit 1
                       set) must have the
                       appropriate semaphore type
                       defined (bit 2 or 3 set).
                       SemSetup requests which do
                       not have the semaphore type
                       properly defined (bit 2 or
                       3 set, but not both) are
                       returned to the caller with
                       a ReturnCode value of
                       PowerBadFlags.

                       Requests which are not
                       manipulating the semaphore
                       resource must have the
                       NoSemFlag bit set and all
                       other bits clear. Requests
                       which do not conform to
                       this requirement will be
                       returned to the caller with
                       a ReturnCode value of
                       PowerBadFlags.

                       SemHandle is a semaphore
                       handle created for Power
                       Management Event
                       Notifications. This
                       function supports the use
                       of 16-bit, system
                       semaphores or 32-bit, event
                       semaphores. When a
                       semaphore is being added to
                       the resource set the
                       appropriate bits must be
                       specified, in the ReqFlags
                       field, to define the
                       semaphore type. This field
                       value is not required if
                       the caller's request is not
                       involved in setup or
                       removal of a semaphore
                       resource.

                       Notes:

                       1.  If using a 16-bit
                           semaphore you must use
                           a 16-bit, system
                           semaphore.  RAM
                           semaphores are not
                           supported.

                       2.  If using a 32-bit,
                           event semaphore, the
                           resource must be
                           created with the
                           "Shared" attribute so
                           the Power Management
                           subsystem can access it
                           at any time.

                       EventMask is a bit mask
                       which defines the specific
                       event messages allowed to
                       be written into the
                       caller's event queue.  The
                       following bits are defined
                       for the EventMask field:

                         Bit #    Meaning If Set
                         -----    -------------------------
                          3       Enable Power Management
                          4       Disable Power Management
                          5       Restore BIOS Defaults
                          6       Set Power State
                          7       Battery Low Event
                          8       Normal Resume Event
                          9       Critical Resume Event

                         All other bits are reserved and must be 0.

                       If any of the reserved bits
                       in the EventMask field are
                       set (value = 1) then the
                       request will fail with a
                       ReturnCode value of
                       PowerBadReserved.

             Data Packet Format
                       All data packet fields are
                       output fields for this
                       function.

                         Field                Length
                         ----------------     ------
                         ReturnCode           WORD

                       ReturnCode is the
                       function-specific
                       completion value.  The
                       valid return values are:

                       o   PowerNoError
                           (0000H)
                       o   PowerBadReserved
                           (0002H)
                       o   PowerSemAlreadySetup
                           (0005H)
                       o   PowerBadFlags
                           (0006H)
                       o   PowerBadSemHandle
                           (0007H)
                       o   PowerRAMSemaphore
                           (000DH)

             Returns
                       The ReturnCode field in the
                       Data Packet.

                       When an error condition is
                       encountered with an input
                       packet field (Parameter or
                       Data) the INVALID_PARAMETER
                       IOCtl error code (8113H) is
                       returned to the caller. The
                       caller must then inspect
                       the Data Packet's
                       ReturnCode field to
                       determine the specific
                       nature of the failure.

             Remarks
                       A set of Power Management
                       resources is allocated when
                       an application calls this
                       IOCtl.  This resource set
                       consists of a queue which
                       holds Power Management
                       event messages.  On an
                       overflow condition, the
                       event queue will not wrap,
                       and consequently will not
                       overwrite the oldest event
                       messages.  There is no
                       error notification in this
                       case.  Only one resource
                       set (event queue) can be
                       created per file handle.

                       If a semaphore is
                       established, the caller is
                       notified (that is, the
                       semaphore is cleared) each
                       time a Power Management
                       event message is added to
                       the queue.  It is the
                       responsibility of the
                       calling application to
                       reset the semaphore.  Since
                       different applications
                       might be interested in
                       different event messages,
                       the EventMask can be
                       tailored to specify only
                       those event messages the
                       application is interested
                       in processing.  The
                       resource set is freed when
                       a DosClose is performed on
                       the associated file handle.

                       If the resource set is
                       defined without a
                       semaphore, the IOCtl 40H
                       interface must be polled to
                       determine if any events
                       have occurred (that is, if
                       any event messages are in
                       the queue).

                       When a semaphore handle has
                       been provided, all
                       subsequent Setup requests
                       for that resource set will
                       fail with a ReturnCode
                       value of
                       PowerSemAlreadySetup,
                       unless a corresponding
                       SemRemoval request has been
                       processed.

                       If an input semaphore
                       handle value is rejected by
                       the DevHlp semaphore
                       management functions the
                       request will fail with a
                       ReturnCode value of
                       PowerBadSemHandle.

   Function 60H - Query Power Status

             This function returns the current
             power state information for the
             system and system devices.

             Parameter Packet Format
                       The majority of the
                       parameter packet fields are
                       output fields for this
                       function. The exception is
                       the ParmLength field which
                       is both input and output.

                         Field                Length
                         ----------------     ------
                         ParmLength           WORD
                         PowerFlags           WORD
                         ACStatus             BYTE
                         BatteryStatus        BYTE
                         BatteryLife          BYTE

                       ParmLength contains the
                       size of the Parameter
                       Packet in bytes (including
                       ParmLength).  On input, it
                       must be a fixed value of 7
                       bytes.

                       PowerFlags is a bit mask
                       with the following bit
                       definition:

                         Bit #    Meaning
                         -----    --------------------------------------
                          0       Power Management State

                         All other bits are reserved and must be 0.

                       If the Power Management
                       State (bit 0) is set
                       (value=1) then Power
                       Management support is
                       currently enabled. If the
                       Power Management State is
                       reset (value=0) then Power
                       Management support is
                       currently disabled.

                       Note:  The Power Management
                       subsystem interfaces remain
                       available even when the
                       support has been disabled
                       (via the Send Power Event
                       IOCtl).  However, the
                       status data returned in the
                       other Parameter Packet
                       fields for this request may
                       not contain meaningful data
                       values.

                       ACStatus contains the
                       status value for the AC
                       line power source.
                       Supported values are:

                       o   0 = AC Off-line
                       o   1 = AC On-line
                       o   255 = Unknown

                       All other values are
                       reserved.

                       BatteryStatus contains the
                       status value for the DC
                       battery power source.
                       Supported values are:

                       o   0 = High
                       o   1 = Low
                       o   2 = Critical
                       o   3 = Charging
                       o   255 = Unknown

                       All other values are
                       reserved.

                       BatteryLife contains the
                       remaining power level for
                       the DC battery power
                       source. Supported values
                       are:

                       o   0 to 100 = Percentage
                           of battery life
                           remaining
                       o   255 = Unknown

                       All other values are
                       reserved.

             Data Packet Format
                       All data packet fields are
                       output fields for this
                       function.

                         Field                Length
                         ----------------     ------
                         ReturnCode           WORD

                       ReturnCode is the
                       function-specific
                       completion value.  The
                       valid return values are:

                       o   PowerNoError
                           (0000H)
                       o   PowerBadLength
                           (0008H)

             Returns
                       Both Parameter and Data
                       Packets contain return
                       information.

                       When an error condition is
                       encountered with an input
                       packet field (Parameter or
                       Data) the INVALID_PARAMETER
                       IOCtl error code (8113H) is
                       returned to the caller. The
                       caller must then inspect
                       the Data Packet's
                       ReturnCode field to
                       determine the specific
                       nature of the failure.

             Remarks
                       On input, the ParmLength
                       field indicates the size of
                       the Parameter Packet in
                       bytes. On output, the
                       ParmLength field indicates
                       either the number of bytes
                       written (without error) or
                       the minimum required size
                       for the function (with
                       PowerBadLength error code
                       value) to complete.

                       On input, ParmLength must
                       be a fixed value of 7
                       bytes.

   Function 61H - Query Power Event

             This function returns Power
             Management Event information queued
             in the Power Management Services
             subsystem.

             Parameter Packet Format
                       The majority of the
                       parameter packet fields are
                       output fields for this
                       function. The exception is
                       the ParmLength field which
                       is both input and output.

                         Field                Length
                         ----------------     ------
                         ParmLength           WORD
                         MsgCount             WORD
                         ulParm1              DWORD
                         ulParm2              DWORD

                       ParmLength contains the
                       size of the Parameter
                       Packet in bytes (including
                       ParmLength).  On input, it
                       must be a fixed value of 12
                       bytes.

                       MsgCount--on output,
                       indicates the number of
                       remaining queue elements
                       currently queued. On input,
                       this field value is
                       undefined.

                       The ulParm1 and ulParm2
                       fields are used the same as
                       defined for the Power
                       Management event messages.
                       See Figure 1 and POWER
                       MANAGEMENT EVENT MESSAGES,
                       earlier in this document,
                       for further details.

             Data Packet Format
                       All data packet fields are
                       output fields for this
                       function.

                         Field                Length
                         ----------------     ------
                         ReturnCode           WORD

                       ReturnCode is the
                       function-specific
                       completion value.  The
                       valid return values are:

                       o   PowerNoError
                           (0000H)
                       o   PowerBadLength
                           (0008H)

             Returns
                       Both Parameter and Data
                       Packets contain return
                       information.

                       When an error condition is
                       encountered with an input
                       packet field (Parameter or
                       Data) the INVALID_PARAMETER
                       IOCtl error code (8113H) is
                       returned to the caller. The
                       caller must then inspect
                       the Data Packet's
                       ReturnCode field to
                       determine the specific
                       nature of the failure.

             Remarks
                       On input, the ParmLength
                       field indicates the size of
                       the Parameter Packet in
                       bytes. On output, the
                       ParmLength field indicates
                       either the number of bytes
                       written (without error) or
                       the minimum required size
                       for the function (with
                       PowerBadLength error code
                       value) to complete.

                       On input, ParmLength must
                       be a fixed value of 12
                       bytes.

   Function 62H - QueryPowerInfo

             This function returns the Power
             Management subsystem and BIOS
             configuration information.

             Parameter Packet Format
                       The majority of the
                       parameter packet fields are
                       output fields for this
                       function. The exception is
                       the ParmLength field which
                       is both input and output.

                         Field                Length
                         ----------------     ------
                         ParmLength           WORD
                         BIOSFlags            WORD
                         BIOSVersion          WORD
                         SubsysVersion        WORD

                       ParmLength contains the
                       size of the Parameter
                       Packet in bytes (including
                       ParmLength).  On input, it
                       must be a fixed value of 8
                       bytes.

                       BIOSFlags is a bit mask
                       field with the bit
                       definitions and setting as
                       queried at system
                       initialization.  For
                       specific bit definitions
                       consult the appropriate APM
                       BIOS Technical Reference
                       materials for the system
                       unit.

                       BIOSVersion is a complex
                       field composed of two BYTE
                       values. These values are:

                       o   The high BYTE contains
                           the APM BIOS major
                           revision level value.

                       o   The low BYTE contains
                           the APM BIOS minor
                           revision level value.

                       A combined WORD value of
                       zero indicates no APM BIOS
                       support is active or
                       available. For specific
                       version number meaning
                       consult the appropriate
                       BIOS Technical Reference
                       materials for the system
                       unit.

                       SubsysVersion is a complex
                       field composed of two BYTE
                       values. These values are:

                       o   The high BYTE contains
                           the subsystem's major
                           revision level value.

                       o   The low BYTE contains
                           the subsystem's minor
                           revision level value.

                       For the first release of
                       the Power Management
                       subsystem the Major
                       revision level value is one
                       (1) and the Minor revision
                       level is zero (0).

             Data Packet Format
                       All data packet fields are
                       output fields for this
                       function.

                         Field                Length
                         ----------------     ------
                         ReturnCode           WORD

                       ReturnCode is the
                       function-specific
                       completion value.  The
                       valid return values are:

                       o   PowerNoError
                           (0000H)
                       o   PowerBadLength
                           (0008H)

             Returns
                       Both Parameter and Data
                       Packets contain return
                       information.

                       When an error condition is
                       encountered with an input
                       packet field (Parameter or
                       Data) the INVALID_PARAMETER
                       IOCtl error code (8113H) is
                       returned to the caller. The
                       caller must then inspect
                       the Data Packet's
                       ReturnCode field to
                       determine the specific
                       nature of the failure.

             Remarks
                       On input, the ParmLength
                       field indicates the size of
                       the Parameter Packet in
                       bytes. On output, the
                       ParmLength field indicates
                       either the number of bytes
                       written (without error) or
                       the minimum required size
                       for the function (with
                       PowerBadLength error code
                       value) to complete.

                       On input, ParmLength must
                       be a fixed value of 8
                       bytes.


DOSSHUTDOWN API
_______________

   The DosShutDown API has been enhanced to assist
   in the Power Management activities within the
   operating system.

   This API is documented in the Control Program
   Programming Reference on page 2-339.  The
   primary change is to rename the ulReserved
   parameter to ShutDownValue.  In addition, the
   valid ShutDownValue parameter values are
   defined as:

     Value       Definition
     -----       ----------------------------------------------------
       0         Perform full system shut down and file system lock.
       1         Perform buffer and cache flushing to make the system
                 quiescent.

     All other values are reserved.

   The Remarks section of the DosShutDown API
   should be updated to qualify the existing text
   as applicable to the ShutDownValue parameter
   value of 0.  Also, the Remarks for the
   ShutDownValue parameter value of 1 should
   indicate that the system should be quiescent
   (that is, no threads of execution will be
   active) at the end of this function request,
   but that the file systems will not be locked
   and processing can resume again at a later
   time.


NOTICES
_______

   References in this publication to IBM products,
   programs, or services do not imply that IBM
   intends to make these available in all
   countries in which IBM operates.  Any reference
   to an IBM product, program or service is not
   intended to state or imply that only IBM's
   product, program, or service may be used.  Any
   functionally equivalent product, program, or
   service that does not infringe any of IBM's
   intellectual property rights or other legally
   protectible rights may be used instead of the
   IBM product, program, or service.  Evaluation
   and verification of operation in conjunction
   with other products, programs, or services,
   except those expressly designated by IBM, are
   the user's responsibility.

   IBM may have patents or pending patent
   applications covering subject matter in this
   document.  The furnishing of this document does
   not give you any license to these patents.  You
   can send license inquiries, in writing, to the
   IBM Director of Commercial Relations, IBM
   Corporation, Purchase, NY 10577.


TRADEMARKS AND SERVICE MARKS

   The following terms, denoted by an asterisk
   (*), used in this publication, are trademarks
   or service marks of the IBM Corporation in the
   United States or other countries:

   IBM
   OS/2
   OS/2 2.0


DISCLAIMER AND COPYRIGHT NOTICE

   IBM DISCLAIMS ALL WARRANTIES, WHETHER EXPRESSED
   OR IMPLIED, INCLUDING WITHOUT LIMITATION,
   WARRANTIES OF FITNESS AND MERCHANTABILITY WITH
   RESPECT TO THE INFORMATION IN THIS DOCUMENT.
   BY FURNISHING THIS DOCUMENT, IBM GRANTS NO
   LICENSES TO ANY RELATED PATENTS OR COPYRIGHTS.

   Copyright IBM Corporation, 1992, all rights
   reserved.

